home *** CD-ROM | disk | FTP | other *** search
/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / os30 / wb / ProcurePens.lha / ProcurePens.DOC < prev    next >
Text File  |  1993-10-16  |  6KB  |  155 lines
  1.  
  2. PROCUREPENS and SETPENS
  3. ~~~~~~~~~~~~~~~~~~~~~~~
  4. Color setting software for AGA and Workbench release 3.0 (V39) or higher.
  5.  
  6.  
  7. Copyright ©1993 by Joseph Luk.  All rights reserved.
  8.  
  9. ----------------------------------------------------------- MAIN DOCUMENTATION
  10.  
  11. Introduction
  12. ~~~~~~~~~~~~
  13. With the release of the AGA systems, Commodore included a wonderful new
  14. version of the operating system which took advantage of the new chips'
  15. extended color selection.  Workbench 3.0 is able to open the screen in
  16. any number of colors from 2 to 256, but it only allows eight of them
  17. to be defined for its use (for icons, etc).  Workbench 2.0 to 2.1 allowed
  18. you to define sixteen.  Go figure.
  19.  
  20. Anyway, the only thing really preventing you from using more than eight
  21. colors is the fact that the Palette Preferences only defines that number.
  22. The rest are left over for other programs to use in Workbench 3.0's palette
  23. sharing scheme.  This is where ProcurePens and the related SetPens comes in.
  24.  
  25.  
  26. What ProcurePens does
  27. ~~~~~~~~~~~~~~~~~~~~~
  28. ProcurePens uses the V39 graphics.library function ObtainPen() to lock, or
  29. procure, a pen.  The idea here is that you call this program from your
  30. user-startup, so that it gets run every time you boot.  This way, you can
  31. have a standard setup for colors beyond the eight that Palette Preferences
  32. allows.  You can lock all available pens for exclusive use, if you wanted to.
  33.  
  34. With the pens locked and set on startup, you can use those extra colors
  35. in Workbench icons (though you may have to use IconEdit 2.x to get them
  36. to work in 16 colors), Dock icons, console escape colors (multicolor CLI
  37. prompts), and other cool stuff.
  38.  
  39. What SetPens does
  40. ~~~~~~~~~~~~~~~~~
  41. SetPens is a somewhat stripped-down version of ProcurePens which does not
  42. lock pens.  Instead, it uses SetRGB32() which simply sets the pen colors.
  43. It reads the same config file as ProcurePens, but, as stated above, merely
  44. sets the colors and does not lock them in any way.  It also doesn't observe
  45. locking rules when it sets the pens; it can redefine colors that are in
  46. use by some other program, so use cautiously.
  47.  
  48. Quick Start
  49. ~~~~~~~~~~~
  50. Okay, enough talk for now.  Open your Workbench in 16 or more colors, pop
  51. a CLI, go to the directory which you extracted this archive in, and type:
  52.  
  53. ProcurePens SampleConfig
  54.  
  55. If pens 4, 5, 6, or 7 are available (not locked by another program),
  56. ProcurePens should tell you that it has set all the pens to the colors
  57. specified in the config file.  Hit [CTRL-C] to remove the program and
  58. its locks.
  59.  
  60.  
  61. Usage
  62. ~~~~~
  63. Typing ProcurePens ? will give you its template:
  64.  
  65.    CONFIGFILE/A,HEX/S,EXCLUSIVE/S,PUBSCREEN/K,LOCKSCREEN/S,VERBOSE/S,DEBUG/S:
  66.    
  67. Items are as follows:
  68.    
  69.    CONFIGFILE - filename of the required configuration file.  The format is
  70.       as follows:
  71.          Header Line: "ProcurePens Config File"
  72.          
  73.          Line 1: pen number to lock
  74.          Line 2: 8-bit red value (defaults to decimal)
  75.          Line 3: 8-bit green value
  76.          Line 4: 8-bit blue value
  77.          Line 5: delimeter (---)
  78.          
  79.          Lines 1-5 define a specifier that ProcurePens will use to lock and
  80.          set the pen.  These repeat until you place "END" as the final
  81.          delimeter.  (see the SampleConfig for an example)
  82.          
  83.    HEX/S - Specify this keyword to indicate that the 8-bit color values
  84.       in the config file are hexadecimal numbers.
  85.       
  86.    EXCLUSIVE/S - Specify this to lock the pens in "exclusive" mode.  Not really
  87.       useful, since all this means is that another program requesting the
  88.       same or a close color won't be able to use the pen.
  89.       
  90.    PUBSCREEN/K - Name of the public screen to perform the operation on.
  91.       Defaults to "Workbench".
  92.       
  93.       Example: PUBSCREEN=SomebodysScreen1
  94.       
  95.    LOCKSCREEN/S - ProcurePens performs a LockPubScreen() to get the address
  96.       of the screen, so that it can do its stuff.  By default, it will unlock
  97.       the screen (allowing you to change screenmodes, etc) when it is done and
  98.       re-lock the screen when it needs to be removed.  Specify this switch
  99.       to prevent this from happening.
  100.       
  101.    VERBOSE/S - some extra info   
  102.    
  103.    DEBUG/S - some more extra info.  :>
  104.    
  105.  
  106.  
  107. More often than not, you will want to call ProcurePens from your user-startup.
  108. In this case, simply launch the program as a seperate task:
  109.    
  110.    run >NIL: ProcurePens <config-file> <options>
  111.    
  112. Note that all console output from the program is supressed in this form,
  113. so errors won't be reported.  Best advice is to try it out before dropping
  114. it in your user-startup.
  115.  
  116. To remove it (normally you'd leave ProcurePens alone since removing it can
  117. subject your onscreen colors to change), simply find its process number
  118. (use Status), and Break it.
  119.  
  120. Example: Break 3
  121. (if ProcurePens is process 3)
  122.  
  123. --
  124.  
  125. SetPens works similarly, except it doesn't stay resident because it doesn't
  126. retain locks on the colors.  As such, you won't need the LOCKSCREEN switch.
  127. Furthermore, it doesn't lock pens, so there's no EXCLUSIVE switch either.
  128. It was also written later, so DEBUG and VERBOSE have been pruned too.  :>
  129.  
  130. Note that SetPens uses the same config file as ProcurePens, and this
  131. file must begin with "ProcurePens Config File".
  132.  
  133.  
  134.  
  135. Et Al
  136. ~~~~~
  137.  
  138. I hope you find these programs useful.  They're all set to localize, so if
  139. anyone wants to see them use locale.library, I'd be happy to do it.  Bug
  140. reports, suggestions, fan mail, secrets of the Universe, etc should be
  141. sent to:
  142.  
  143. Joseph Luk
  144.  
  145. Internet: jluk@eis.calstate.edu
  146. GEnie: J.LUK
  147.  
  148. S-mail:   San Francisco, CA 94188-4401    U.S.A.    (no address is necessary)
  149.  
  150.  
  151. BTW, in case you're wondering, this is my gift to you.  If you use these
  152. programs regularly, I'd *LOVE* to get a postcard from you though!  :>
  153.  
  154. --
  155.